docs: document hotfix backports and preview release versioning - #569
Open
Corina (corinagum) wants to merge 3 commits into
Open
docs: document hotfix backports and preview release versioning#569Corina (corinagum) wants to merge 3 commits into
Corina (corinagum) wants to merge 3 commits into
Conversation
RELEASE.md covered cutting a new release from main, but had nothing for backporting a fix onto an existing release branch, and nothing about how preview versions are numbered. Both gaps came up shipping 2.0.16 and 2.1.0-alpha.2 for the same fix. - Branch strategy now shows both live trains and their PyPI dist-tags - New section for cherry-picking a fix onto a release branch - New section on preview versioning: the height rules, the versionHeightOffset formula, and a worked example - Call out that preview backports must be merged with a merge commit, since squashing lowers the height and republishes an existing version - Add a pre-publish nbgv verification step and a post-publish check - Correct the claim that release PRs are squash-merged - Refresh stale version examples Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 36f4a7c0-71cb-4b9d-8a5c-d6db706ff8a7
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the release process documentation to cover hotfix backports onto long-lived release branches and to explain preview (alpha) versioning/numbering for the release/v2.1 train, aligning the written process with how the repository’s NBGV + publish pipeline actually behave.
Changes:
- Documented a cherry-pick based backport workflow for releasing a fix already merged to
mainonto an existingrelease/vX.Ybranch. - Added a detailed “Preview releases” section explaining commit-height-derived alpha numbering and how to compute
versionHeightOffset, including a worked example. - Refreshed branch strategy/version examples and updated GitHub release guidance for preview releases.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The cherry-pick step called the source commit a merge commit, but PRs into main are squash-merged, which produces an ordinary single-parent commit. Rename the placeholder, explain how to find the commit by PR number, and make the -m 1 guidance conditional on an actual merge commit. Also name the asymmetry with release-branch PRs, which do require merge commits. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 36f4a7c0-71cb-4b9d-8a5c-d6db706ff8a7
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 36f4a7c0-71cb-4b9d-8a5c-d6db706ff8a7
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Shipping the
channelDatafix (#564) to both live release trains, as 2.0.16 and 2.1.0-alpha.2, surfaced several gaps inRELEASE.md.The doc only describes cutting a new release from
main: branch off main, bumpversion.json,git merge -s ours. There was no procedure for the more common case, where a fix has already landed onmainand needs to ship on an existing release line. Following the documented flow for a hotfix would sweep all ofmaininto the release branch, turning a one-line fix into an untested release.Nothing documented how preview versions on
release/v2.1are numbered either. The2.1.0-alpha.{height}scheme computes the version from commit height, soversionHeightOffsethas to be set to a value that depends on a merge commit that does not exist yet. Getting it wrong republishes a version already on PyPI. Working that out required reverse-engineering the previous backport (#544) from git history.What changed
release/v2.0stable,release/v2.1preview) with their PyPI dist-tags, and notes that a fix affecting both needs a separate backport and release for each.versionHeightOffset = target_alpha - final_merge_heightformula, and a worked example using the real numbers from 2.1.0-alpha.2.version.jsonstays as-is once a release ships. A stable branch keeps its literal version and the next release PR bumps it; a preview branch increments{height}on its own. Sitting on an already-published stable version is deliberate, since PyPI rejecting a duplicate upload is the only guard against an accidental publish.main. Squashing lowers the final height and makes the pipeline republish an existing version.nbgv get-version -v SemVer2before triggering a Public run, and a post-publish check that a preview did not displace thelatesttag. Plus a tip for confirming the number before merging by simulating the merge on a locally-namedrelease/vX.Ybranch, which matters becausepublicReleaseRefSpecmatches on branch name.--prereleasefor preview GitHub releases.Notes
Docs-only. No code, dependency, or pipeline changes.
Claims here were verified against the repo rather than assumed: the height math was checked with
nbgvagainst #544 and the 2.1.0-alpha.2 release, the squash-merge behavior by parent counts onmain, and the dist-tag and duplicate-guard behavior by reading.azdo/publish.yml.